home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Celestin Apprentice 5
/
Apprentice-Release5.iso
/
Source Code
/
Libraries
/
strlist3
/
411 Files
/
StrListHelp
next >
Wrap
Text File
|
1996-02-26
|
42KB
|
1,258 lines
æKY CopyrightNoticeStrListHelp
æC -----
StrListHelp Copyright (c) 1995, 1996 by John Montbriand. All rights reserved.
æKY StrListHelp
æKL StrList.h
æKY StrList.h
StrList
æC -----
Routines for working with string lists.
Copyright (c) 1995, 1996 by John Montbriand. All rights reserved.
creating string lists: retrieving STR# resources:
NewStringList GetStringList
MakeStringList Get1StringList
retrieving information: recovering storage:
StringListSize DisposeStringList
StringListElt
RetrieveIndString sorted map access:
mapped access: MakeSortedStringListMap
MakeStringListMap WithSortedStringList
MapStringListElt
WithStringList adding new strings:
StringListInstall
deleting strings: StringListAppend
StringListRemove StringListPrepend
ClearStringList
finding strings:
adding strings to sorted lists: FindStringList
StringListInsert
StringListRInsert operations on sets of strings:
StringListUnion
string list -> menu handle: StringListIntersection
StringListToMenu StringListDifference
StringListSubset
string list -> ListHandle StringListEquivalent
StringListToList
æKY NewStringList
æFc strlist.h
æMM
æD Handle NewStringList(void);
æDT Handle st = NewStringList();
æT Function
æC -----
for creating a new, empty string list.
arguments:
none
return value:
A Handle containing a empty string list.
if an error occurs, NULL is returned.
description:
NewStringList creates a new string list handle in the current
heap zone. The string list created contains no strings, and the
count value is set to zero.
example application:
In this example, we create a new, empty string list:
{ Handle my_string_list;
my_string_list = NewStringList();
...
notes:
you can call DisposeHandle to dispose of a string list created by
NewStringList.
æKY MakeStringList
æFc strlist.h
æMM
æD Handle MakeStringList(long n, ...);
æDT Handle st = MakeStringList((long) n, ...);
æT Function
æC -----
for creating a string list with elements specified as arguments.
arguments:
n = the number of c style strings that follow in the ... parameter list
... = n c style strings
return value:
A Handle to a string list containing the strings specified in the ...
parameter list in the same order as they were provided as parameters.
if an error occurs, NULL is returned.
description:
MakeStringList creates a new string list handle in the current
heap zone containing the strings provided as parameters. the
number of strings provided as parameters must match the number
of specified in the value n. if an error occurs, NULL is returned.
example application:
in this example we create a string list containing 5 elements:
{ Handle my_string_list;
my_string_list = MakeStringList(5, "this", "is", "a", "string",
"list");
...
notes:
you can call DisposeHandle to dispose of a string list created by
MakeStringList.
æKY GetStringList
æFc strlist.h
æMM
æD Handle GetStringList(short id);
æDT Handle st = GetStringList((short) id);
æT Function
æC -----
for retrieving a string list from a resource file.
arguments:
id = the resource id of the STR# resource containing the string list
return value:
A Handle to a string list resource or NULL if an error occurs.
description:
GetStringList is equivalent to GetResource('STR#', id).
example application:
in this example, we retrieve the string list with id 128:
{ Handle my_string_list;
my_string_list = GetStringList(128);
...
notes:
you should not call DisposeHandle to dispose of a string list
retrieved by GetStringList as such string lists are registed
in the resource file. Instead, after you are done with the string
list call ReleaseResource(<the string list>).
You can call DisposeStringList on a string list created by
GetStringList.
æKY Get1StringList
æFc strlist.h
æMM
æD Handle Get1StringList(short id);
æDT Handle st = Get1StringList((short) id);
æT Function
æC -----
for retrieving a string list from the current resource file.
arguments:
id = the resource id of the STR# resource containing the string list
return value:
A Handle to a string list resource or NULL if an error occurs.
description:
Get1StringList is equivalent to Get1Resource('STR#', id) and hence
it only searches the current resource file for string list resources.
example application:
in this example, we retrieve the string list with id 128
searching only the current resource file:
{ Handle my_string_list;
my_string_list = GetStringList(128);
...
notes:
you should not call DisposeHandle to dispose of a string list
retrieved by Get1StringList as such string lists are registed
in the resource file. Instead, after you are done with the string
list call ReleaseResource(<the string list>).
You can call DisposeStringList on a string list created by
GetStringList.
æKY DisposeStringList
æFc strlist.h
æMM
æD void DisposeStringList(Handle list);
æDT DisposeStringList((Handle) list);
æT Procedure
æC -----
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
return value:
none.
description:
DisposeStringList recovers the memory occupied by a string list.
After determining if the handle refers to a resource by checking
the handle's flag values, DisposeStringList either calls
ReleaseResource for resource handles or calls DisposeHandle
for regular handles.
example application:
Here, we a get a string list from a resource file, and
and do away with it, then we create a new string list and
do away with it as well. Note: DisposeStringList does
the right thing in both cases calling ReleaseResource for
the resource handle and calling DisposeHandle for the list
we allocated in memory ourselves.
{ Handle my_string_list;
my_string_list = GetStringList(128);
if (my_string_list != NULL) {
...some statements using the string list...
DisposeStringList(my_string_list);
}
my_string_list = MakeStringList(5, "this", "is", "a",
"string", "list");
if (my_string_list != NULL) {
...some statements using the string list...
DisposeStringList(my_string_list);
}
...
notes:
none.
æKY StringListSize
æFc strlist.h
æMM
æD short StringListSize(Handle list);
æDT short the_size = StringListSize((Handle) list);
æT Function
æC -----
for retrieving the size of a string list.
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
return value:
the number of strings contained in the string list parameter.
description:
StringListSize returns the value stored in the count field of the
string list handle. the number returned corresponds to the number
of strings stored in the list.
example application:
here we get a string list resource and calculate it's size.
{ Handle my_string_list;
short number_of_strings;
my_string_list = GetStringList(128);
number_of_strings = StringListSize(my_string_list);
...
notes:
none.
æKY StringListElt
æFc strlist.h
æMM
æD StringPtr StringListElt(Handle list, short elt);
æDT StringPtr the_string = StringListElt((Handle) list, (short) elt);
æT Function
æC -----
for retrieving a pointer to a string in a string list.
formal declaration:
StringPtr StringListElt(Handle list, short elt);
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
elt = the index of the string list element. remember, elements
in string lists are indexed 1, 2, 3, ..., n.
return value:
a pointer to the requested string list element or NULL if elt.
description:
StringListElt returns a pointer to a specific element in the string
list handle. The pointer returned refers directly to the data inside
of the string list handle.
example application:
Here, we draw every element in a string list. Note the calls
to HLock and HUnlock surrounding the part where we access the
strings.
{ Handle my_string_list;
short number_of_strings, index;
StringPtr a_string;
my_string_list = GetStringList(128);
number_of_strings = StringListSize(my_string_list);
HLock(my_string_list); /* lock the handle so it does not move */
for (index = 1; index <= number_of_strings; index++) {
a_string = StringListElt(my_string_list, index);
MoveTo(10, index*20);
DrawString(a_string);
}
HUnlock(my_string_list);
...
notes:
StringListElt returns a pointer that refers to data stored inside
of the string list handle. Some toolbox calls can cause handles
to move in memory and invalidate this pointer unless the string
list handle is locked. Also, the pointer returned may not always
be alligned at an even address.
Each call to StringListElt involves a linear search of the string
list for the element requested. If you are frequently accessing
strings stored in a string list and you are noticing a performance
dropoff because of this, then you should call MakeStringListMap
and access the strings directly using the MapStringListElt routine
(StringListElt is uses O(n) time per lookup while MapStringListElt
uses O(k) time per lookup). For example, the example application
in StringListElt requires O(n*n) time while the example application
of MakeStringListMap only requires O(n) time for the same task, and
MakeSortedStringListMap only requires O(nlogn) time.
æKY RetrieveIndString
æFc strlist.h
æMM
æD void RetrieveIndString(Handle list, short elt, StringPtr the_string);
æDT StringPtr st = RetrieveIndString((Handle) width, (short) elt, (StringPtr) the_string);
æT Function
æC -----
for retrieving a string from a string list handle.
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
elt = the index of the string list element. remember, elements
in string lists are indexed 1, 2, 3, ..., n.
the_string = a pointer to a variable of type Str255 to copy
the string into.
return value:
the_string, or NULL if the elt was out of bounds.
description:
RetrieveIndString copies the indicated string list element from
the string list into the string pointed to by the_string.
RetrieveIndString returns the value passed in the third
parameter, or NULL if the index was out of bounds.
example application:
here, we copy element 4 from the string list into the
string variable my_string:
{ Handle my_string_list;
Str255 my_string;
my_string_list = GetStringList(128);
RetrieveIndString(my_string_list, 4, my_string);
...
notes:
you do not have to lock the string list when using this
call to retrieve string list elements.
æKY MakeStringListMap
æFc strlist.h
æMM
æD StringPtr** MakeStringListMap(Handle list);
æDT StringPtr **the_map = MakeStringListMap((Handle) list);
æT Function
æC -----
for making a list of pointers referring to elements in a string list.
formal declaration:
StringPtr** MakeStringListMap(Handle list);
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
return value:
a handle to an array of string pointers.
description:
MakeStringListMap creates an array of string pointers referring to
consecutive string list elements. The string list is locked high in
the heap before the mapping array is created. A map created in this
way can be used to directly access string list elements using the
function MapStringListElt without the linear search overhead required
by StringListElt.
example application:
in this example, we use a string list map to consecutively
draw string list elements on the screen.
{ Handle my_string_list;
StringPtr** the_map, the_string;
short number_of_strings, i;
my_string_list = NewStringList();
...several hundred strings are added here...
the_map = MakeStringListMap(my_string_list);
if (the_map != NULL) {
number_of_strings = StringListSize(my_string_list);
for (i=1; i <= number_of_strings; i++) {
the_string = MapStringListElt(the_map, i);
MoveTo(10, i*10);
DrawString(the_string);
}
HUnlock(my_string_list);
DisposeHandle((Handle) the_map);
}
...
notes:
a map created by MakeStringListMap can be disposed of with
a call to DisposeHandle((Handle) the_map).
Since MakeStringListMap locks the string list handle, you
should remember to unlock the handle once you dispose of the map.
also note:
do not unlock the string list handle until you are completely
done with the map--unlocking the string list will invalidate
pointers stored in the map.
æKY MakeSortedStringListMap
æFc strlist.h
æMM
æD StringPtr** MakeSortedStringListMap(Handle list);
æDT StringPtr **the_map = MakeSortedStringListMap((Handle) list);
æT Function
æC -----
for making a list of pointers referring to elements in a string list
in alphabetical order.
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
return value:
a handle to an array of string pointers with the pointers sorted
so that the map refers to the strings in the string list in
alphabetical order. if SLUSECASE is true, case sensitive ordering
is used.
description:
MakeSortedStringListMap is identical to MakeStringListMap except
that the pointers in the map are sorted so that they refer
to the string in the string list in aphabetical order.
example application:
in this example, we use a string list map to consecutively
draw string list elements on the screen in alphabetical order.
{ Handle my_string_list;
StringPtr** the_map, the_string;
short number_of_strings, i;
my_string_list = NewStringList();
...several hundred strings are added here...
the_map = MakeSortedStringListMap(my_string_list);
if (the_map != NULL) {
number_of_strings = StringListSize(my_string_list);
for (i=1; i <= number_of_strings; i++) {
the_string = MapStringListElt(the_map, i);
MoveTo(10, i*10);
DrawString(the_string);
}
HUnlock(my_string_list);
DisposeHandle((Handle) the_map);
}
...
notes:
a map created by MakeSortedStringListMap can be disposed of with
a call to DisposeHandle((Handle) the_map).
Since MakeSortedStringListMap locks the string list handle, you
should remember to unlock the handle once you dispose of the map.
also note:
do not unlock the string list handle until you are completely
done with the map--unlocking the string list will invalidate
pointers stored in the map.
æKY WithStringList
æFc strlist.h
æMM
æD #define WithStringList(stringlist, map)
æDT WithStringList(((Handle) stringlist), ((StringPtr**) map)) { statement... }
æT Macro
æC -----
for automatic creation of a string list map.
arguments:
stringlist = an value of type string list.
map = a variable of type StringPtr** for use in the macro.
you do not need to initialize this variable, all you do is
declare it.
return value:
not applicable.
description:
WithStringList creates a map for the string list that will be
available for use in the statement immediately following the
macro invocation. In addition, the macro disposes of the map and
unlocks the list once the statement has completed execution. It is
usually most convienient to follow the macro with a compound
statement.
example application:
here, we use the WithStringList macro to create a map then we
use the map to display the strings on the screen.
{ Handle my_string_list;
StringPtr** the_map;
short number_of_strings, index;
my_string_list = MakeStringList(4, "red", "green",
"orange", "blue");
WithStringList(my_string_list, the_map) {
number_of_strings = StringListSize(my_string_list);
for (i=1; i <= number_of_strings; i++) {
MoveTo(10, i*10);
DrawString(MapStringListElt(the_map, i));
}
}
...
notes:
macro parameters may be evaluated more than once in the macro
output so it's best to use variables here as in the above example.
æKY WithSortedStringList
æFc strlist.h
æMM
æD #define WithSortedStringList(stringlist, map)
æDT WithSortedStringList(((Handle) stringlist), ((StringPtr**) map)) { statement... }
æT Macro
æC -----
for automatic creation of a sorted list map.
arguments:
stringlist = an value of type string list.
map = a variable of type StringPtr** for use in the macro.
you do not need to initialize this variable, all you do is
declare it.
return value:
not applicable.
description:
WithSortedStringList creates a map for the string list that will
be available for use in the statement immediately following the
macro invocation. the pointers in the list are sorted so that
the map refers to the strings in the list in alphabetical order.
if SLUSECASE is true, case sensitive comparisons are used in
ordering the map pointers. In addition, the macro disposes
of the map and unlocks the list once the statement has completed
execution. It is usually more convienient to follow the macro
with a compound statement.
example application:
Here, we use the WithSortedStringList macro to create a list of
strings, and then we use the map to display those strings on
the screen in alphabetical order.
{ Handle my_string_list;
StringPtr** the_map;
short number_of_strings, index;
my_string_list = MakeStringList(4, "red", "green",
"orange", "blue");
WithSortedStringList(my_string_list, the_map) {
number_of_strings = StringListSize(my_string_list);
for (i=1; i <= number_of_strings; i++) {
MoveTo(10, i*10);
DrawString(MapStringListElt(the_map, i));
}
}
...
notes:
macro parameters may be evaluated more than once in the macro
output so it's best to use variables here as in the above example.
æKY StringListRemove
æFc strlist.h
æMM
æD void StringListRemove(Handle list, short elt);
æDT StringListRemove((Handle) list, (short) elt);
æT Procedure
æC -----
for removing an element from a string list
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
elt = the index of the string list element. remember, elements
in string lists are indexed 1, 2, 3, ..., n.
return value:
none.
description:
StringListRemove deletes the specified element from the string list
updating the count field appropriately.
example application:
here, we remove element 4 from a string list.
{ Handle my_string_list;
my_string_list = MakeStringList(4, "red", "green",
"orange", "blue");
StringListRemove(my_string_list, 3); /* remove the word "orange" */
...
notes:
none.
æKY ClearStringList
æFc strlist.h
æMM
æD void ClearStringList(Handle list);
æDT ClearStringList((Handle) list);
æT Procedure
æC -----
for removing all elements from a string list
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
return value:
none.
description:
ClearStringList removes all of the strings from the string list
making it an empty list.
example application:
here, we clear the string list so it contains no elements.
{ Handle my_string_list;
my_string_list = MakeStringList(4, "red", "green",
"orange", "blue");
ClearStringList(my_string_list);
...
notes:
none.
æKY StringListInstall
æFc strlist.h
æMM
æD void StringListInstall(Handle list, short elt, StringPtr s);
æDT StringListInstall((Handle) list, (short) elt, (StringPtr) s);
æT Procedure
æC -----
for installing a string in a string list at a particular position.
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
elt = the index where the string list element will be placed.
remember, elements in string lists are indexed 1, 2, 3, ..., n.
s = a pointer to the string to add to the list
return value:
none.
description:
StringListInstall installs a string into the string list at the
indicated element position.
example application:
Here, we insert a string into the list at position 2.
{ Handle my_string_list;
my_string_list = MakeStringList(3, "the", "brown", "fox");
/* my_string_list = ("the", "brown", "fox") */
StringListInstall(my_string_list, 2, "\pquick");
/* my_string_list = ("the", "quick", "brown", "fox") */
...
notes:
none.
æKY StringListAppend
æFc strlist.h
æMM
æD void StringListAppend(Handle list, StringPtr s);
æDT StringListAppend((Handle) list, (StringPtr) s);
æT Procedure
æC -----
for adding a string to the end of a string list.
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
s = a pointer to the string to add to the list
return value:
none.
description:
StringListAppend adds the string s to the end of the string list as
the last element in the list.
example application:
here, we add an element to the end of a string list.
{ Handle my_string_list;
my_string_list = MakeStringList(3, "my", "list", "of");
/* my_string_list = ("my", "list", "of") */
StringListAppend(my_string_list, "\pstrings");
/* my_string_list = ("my", "list", "of", "strings") */
...
notes:
none.
æKY StringListPrepend
æFc strlist.h
æMM
æD void StringListPrepend(Handle list, StringPtr s);
æDT StringListPrepend((Handle) list, (StringPtr) s);
æT Procedure
æC -----
for adding a string to the front of a string list.
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
s = a pointer to the string to add to the list
return value:
none.
description:
StringListPrepend adds the string s to the string list placing it
in the first element position.
example application:
here, we add an element to the front of the string list.
{ Handle my_string_list;
my_string_list = MakeStringList(3, "heap", "of", "strings");
/* my_string_list = ("heap", "of", "strings") */
StringListPrepend(my_string_list, "\pA big");
/* my_string_list = ("A big", "heap", "of", "strings") */
...
notes:
none.
æKY StringListInsert
æFc strlist.h
æMM
æD short StringListInsert(Handle list, StringPtr s);
æDT short where = StringListInsert((Handle) list, (StringPtr) s);
æT Function
æC -----
for adding a string to an alphabetically sorted string list.
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
s = a pointer to the string to add to the list
return value:
the position in the list of strings where the string was installed,
or zero if an error occurs.
description:
StringListInsert adds the string to a string list that is sorted
in ascending, non case sensitive, alphabetical order in such a
way that the list remains sorted after the string has been added.
example application:
in this example we insert the string delta into an alphabetically
sorted string list.
{ Handle my_string_list;
my_string_list = MakeStringList(3, "alpha", "beta", "gamma");
/* my_string_list = ("alpha", "beta", "gamma") */
StringListInsert(my_string_list, "\pdelta");
/* my_string_list = ("alpha", "beta", "delta", "gamma") */
...
notes:
none.
æKY StringListRInsert
æFc strlist.h
æMM
æD short StringListRInsert(Handle list, StringPtr s);
æDT short where = StringListRInsert((Handle) list, (StringPtr) s);
æT Function
æC -----
for adding a string to an alphabetically sorted string list. The list
should be sorted in descending order.
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
s = a pointer to the string to add to the list
return value:
the position in the list of strings where the string was installed,
or zero if an error occurs.
description:
StringListRInsert adds the string to a string list that is sorted
in descending, non case sensitive, alphabetical order in such a
way that the list remains sorted after the string has been added.
example application:
in this example we insert the string delta into an alphabetically
sorted string list. The list is sorted in descending order.
{ Handle my_string_list;
my_string_list = MakeStringList(3, "gamma", "beta", "alpha");
/* my_string_list = ("gamma", "beta", "alpha") */
StringListRInsert(my_string_list, "\pdelta");
/* my_string_list = ("gamma", "delta", "beta", "alpha") */
...
notes:
none.
æKY FindStringList
æFc strlist.h
æMM
æD short FindStringList(Handle list, StringPtr s);
æDT short where = FindStringList((Handle) list, (StringPtr) s);
æT Function
æC -----
find the string in a string list.
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
s = a pointer to the string to find in the list
return value:
the position in the list of strings where the string was found or zero
if the string is not in the list.
description:
FindStringList searches the list of strings in sequential order until
it finds a non case sensitive match for the string. If a match is
the index is returned, otherwise, if there is no match, FindStringList
returns zero.
example application:
Here, we use the FindStringList routine to find the index of the
indicated string.
{ Handle my_string_list;
short position;
my_string_list = MakeStringList(5, "the", "word", "is",
"hidden", "here");
position = FindStringList(my_string_list, "\phidden");
if (position != 0) {
/* position == 4 */
}
position = FindStringList(my_string_list, "\pUnused");
/* position == 0, 'unused' is not in the list */
...
notes:
none.
æKY StringListToMenu
æFc strlist.h
æMM
æD MenuHandle StringListToMenu(Handle list, short id, StringPtr name);
æDT MenuHandle themenu = StringListToMenu((Handle) list, (short) id, (StringPtr) s);
æT Function
æC -----
create a menu containing all of the strings in the string list.
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
id = the menu id for the menu
name = the menu title, NULL is OK.
return value:
the created menu handle.
description:
StringListToMenu creates a new menu handle filling in the menu
items using the strings in the string list. items in the string list
will correspond to items in the menu on a one to one basis.
i.e. string list element one will be the same as menu item one,
and so on, and so on....
example application:
Here, we create a menu for use with the PopUpMenuSelect function..
{ Handle my_string_list;
MenuHandle my_menu;
long result;
short item;
my_string_list = MakeStringList(3, "Red", "Green", "Blue");
my_menu = StringListToMenu(my_string_list, 128, "\pColours");
InsertMenu(my_menu, -1);
result = PopUpMenuSelect(my_menu, 100, 100, 1);
DeleteMenu(128);
if (HiWord(result) != 0) {
item = LoWord(result);
.....
}
...
notes:
by default, StringListToMenu calls SetItem to add the strings into the
menu handle and as such the set of special menu formatting characters
are not interpreted by the menu manager. If you would like to have
the menu formatting characters interpreted when string list elements
are added to menus then you can define the compile time variable
INTERPRETMENUCHARS in the file "strlist.h".
æKY StringListToList
æFc strlist.h
æMM
æD void StringListToList(Handle list, ListHandle the_list);
æDT StringListToList((Handle) list, (ListHandle) the_list);
æT Procedure
æC -----
add strings from a string list to a list handle.
arguments:
list = a handle to a string list created by NewStringList,
MakeStringList, GetStringList, or Get1StringList.
the_list = a list handle
return value:
none.
description:
StringListToList fills in the first column of the ListHandle so
it contains all of the strings from the string list.
example application:
here, we copy a string list into a list manager list.
{ Handle my_string_list;
ListHandle my_list_manager_list;
WindowPtr the_window;
Rect bounds, dataBounds;
Point cSize;
/* set up some stuff */
SetPt(&cSize, 0, 0);
SetRect(&dataBounds, 0, 0, 1, 0);
SetRect(&bounds, 100, 100, 200, 200);
/* make a window */
the_window = NewWindow(NULL, &bounds, "\pstrlist",
true, noGrowDocProc, (WindowPtr) (-1), false, 0);
SetPort(the_window);
/* make a list */
OffsetRect(&bounds, -bounds.left, -bounds.top);
my_list_manager_list = LNew(&bounds, &dataBounds, cSize,
0, the_window, true, false, false, true);
/* make a string list */
my_string_list = MakeStringList(3, "Red", "Green", "Blue");
/* put the string list into the list */
StringListToList(my_string_list, my_list_manager_list);
...
notes:
recall string lists elements are indexed elt = 1, 2, ..., n while
elements contained in ListHandles created by StringListToList are
indexed cell.v = 0, 1, 2, ..., n-1.
æKY StringListUnion
æFc strlist.h
æMM
æD Handle StringListUnion(Handle A, Handle B);
æDT Handle the_union = StringListUnion((Handle) A, (Handle) B);
æT Function
æC -----
calculate the union of two sets of strings.
arguments:
A = a handle to a string list created by NewStringList, MakeStringList,
GetStringList, or Get1StringList.
B = a handle to a string list created by NewStringList, MakeStringList,
GetStringList, or Get1StringList.
return value:
a string list handle.
description:
StringListUnion returns a new string list handle containing all
of the strings that appear in both string list A and string list B,
or NULL if an error occurs. if SLUSECASE is true, case sensitive
comparisons are used. operation = OR
example application:
here, we calculate the union of two sets of strings.
{ Handle A, B, C;
A = MakeStringList(4, "red", "green", "orange", "blue");
B = MakeStringList(4, "yellow", "green", "purple", "blue");
C = StringListUnion(A, B);
/* C now contains:
{"blue", "green", "orange", "purple", "red", "yellow"} */
...
notes:
in the present implementation, the result will be alphabetically
sorted.
æKY StringListIntersection
æFc strlist.h
æMM
æD Handle StringListIntersection(Handle A, Handle B);
æDT Handle the_intersection = StringListIntersection((Handle) A, (Handle) B);
æT Function
æC -----
calculate the intersection of two sets of strings.
arguments:
A = a handle to a string list created by NewStringList, MakeStringList,
GetStringList, or Get1StringList.
B = a handle to a string list created by NewStringList, MakeStringList,
GetStringList, or Get1StringList.
return value:
a string list handle.
description:
StringListIntersection returns a new string list handle containing only
those strings that appear in both string list A and string list B,
or NULL if an error occurs. if SLUSECASE is true, case sensitive
comparisons are used. operation = AND
example application:
here, we calculate the intersection of two sets of strings.
{ Handle A, B, C;
A = MakeStringList(4, "red", "green", "orange", "blue");
B = MakeStringList(4, "yellow", "green", "purple", "blue");
C = StringListIntersection(A, B);
/* C now contains:
{"blue", "green"} */
...
notes:
in the present implementation, the result will be alphabetically
sorted.
æKY StringListDifference
æFc strlist.h
æMM
æD Handle StringListDifference(Handle A, Handle B);
æDT Handle the_difference = StringListDifference((Handle) A, (Handle) B);
æT Function
æC -----
calculate the difference of two sets of strings.
arguments:
A = a handle to a string list created by NewStringList, MakeStringList,
GetStringList, or Get1StringList.
B = a handle to a string list created by NewStringList, MakeStringList,
GetStringList, or Get1StringList.
return value:
a string list handle.
description:
StringListDifference returns a new string list handle containing all
the strings that do not appear in both A and B. if SLUSECASE is true,
case sensitive comparisons are used. operation = XOR
example application:
here, we calculate the difference of two sets of strings.
{ Handle A, B, C;
A = MakeStringList(4, "red", "green", "orange", "blue");
B = MakeStringList(4, "yellow", "green", "purple", "blue");
C = StringListDifference(A, B);
/* C now contains:
{"orange", "purple", "red", "yellow"} */
...
notes:
in the present implementation, the result will be alphabetically
sorted.
æKY StringListSubset
æFc strlist.h
æMM
æD Boolean StringListSubset(Handle A, Handle B);
æDT Boolean is_subset = StringListSubset((Handle) A, (Handle) B);
æT Function
æC -----
determine if one set is a subset of another.
arguments:
A = a handle to a string list created by NewStringList, MakeStringList,
GetStringList, or Get1StringList.
B = a handle to a string list created by NewStringList, MakeStringList,
GetStringList, or Get1StringList.
return value:
true or false.
description:
StringListSubset returns true if the strings contained in B make up
a subset of the strings contained in A. if SLUSECASE is true,
case sensitive comparisons are used.
example application:
here, we call StringListSubset to determine if B is a subset of A.
{ Handle A, B, C;
A = MakeStringList(4, "red", "green", "orange", "blue");
B = MakeStringList(4, "red", "orange", "blue");
if (StringListSubset(A, B)) {
/* B is infact a subset of A */
}
...
notes:
none.
æKY StringListEquivalent
æFc strlist.h
æMM
æD Boolean StringListEquivalent(Handle A, Handle B);
æDT Boolean the_same = StringListEquivalent((Handle) A, (Handle) B);
æT Function
æC -----
determine if two sets of strings contain the same elements.
arguments:
A = a handle to a string list created by NewStringList, MakeStringList,
GetStringList, or Get1StringList.
B = a handle to a string list created by NewStringList, MakeStringList,
GetStringList, or Get1StringList.
return value:
true or false.
description:
StringListEquivalent returns true if the strings both string lists
contain the same strings. if SLUSECASE is true, case sensitive
comparisons are used.
example application:
here, we call StringListEquivalent to if the two sets are the same.
{ Handle A, B;
A = MakeStringList(4, "red", "green", "orange", "blue");
B = MakeStringList(4, "red", "green", "orange", "blue");
if (StringListEquivalent(A, B)) {
/* yes, the are the same sets */
}
...
notes:
none.
